Skip to content

fix: clarify markdownlint marker placement in PRD Builder#2098

Merged
WilliamBerryiii merged 15 commits into
mainfrom
fix/prd-builder-agent
Jun 26, 2026
Merged

fix: clarify markdownlint marker placement in PRD Builder#2098
WilliamBerryiii merged 15 commits into
mainfrom
fix/prd-builder-agent

Conversation

@jkim323

@jkim323 jkim323 commented Jun 21, 2026

Copy link
Copy Markdown
Collaborator

Pull Request

Description

Clarifies PRD Builder markdown suppression marker placement and aligns the project-planning builder guidance around the consolidated docs/project-planning/ output path.

The original issue focused on PRD Builder wording that could place HTML comments before YAML frontmatter. This update keeps the frontmatter opening delimiter on line 1, moves generated suppression comments immediately after the closing frontmatter delimiter, and brings related PRD, BRD, and shared disclaimer instructions into the same project-planning model.

The workflow check failed in model-validation and from investigation seems like the CI workflows fail intermittently when PSGallery has transient outages during Install-Module. Since every workflow installs modules inline without caching or retry, a single gallery hiccup fails the entire job. The changes for this is large so I'll be creating a follow-up PR for this. To mitigate, I fixed the casing.

Changes

  • Updated PRD Builder to write PRDs under docs/project-planning/, preserve valid YAML frontmatter ordering for generated suppression markers, use normalized phaseSkillsLoaded entries, and ingest upstream BRD_TO_PRD_HANDOFF_V1 coverage context when available.
  • Updated BRD Builder to write BRDs under docs/project-planning/, defer frontmatter and section requirements to canonical requirements-author templates, and align traceability language around business goals, FR-to-BG coverage, BG/DD identifiers, and quality gates.
  • Updated the shared disclaimer-language instruction applyTo pattern to include docs/project-planning/* alongside the relevant planning and review tracking folders.

Related Issue(s)

Fixes #2097

Type of Change

Code & Documentation:

  • Bug fix (non-breaking change fixing an issue)
  • New feature (non-breaking change adding functionality)
  • Breaking change (fix or feature causing existing functionality to change)
  • Documentation update

AI Artifacts:

  • Copilot instructions (.github/instructions/*.instructions.md)
  • Copilot prompt (.github/prompts/*.prompt.md)
  • Copilot agent (.github/agents/*.agent.md)
  • Copilot skill (.github/skills/*/SKILL.md)

Testing

  • Markdown linting: npm run lint:md
  • Frontmatter validation: npm run lint:frontmatter
  • AI artifact validation: npm run lint:ai-artifacts
  • VS Code diagnostics: no errors reported for the changed files

Security Considerations

  • This PR does not contain sensitive information, secrets, credentials, or NDA content.
  • This PR does not add dependencies or change runtime security posture.

Additional Notes

The scope expanded slightly during review to keep PRD Builder, BRD Builder, and the shared disclaimer protocol consistent with the consolidated project-planning document location.

@jkim323 jkim323 requested a review from a team as a code owner June 21, 2026 05:23
@codecov-commenter

codecov-commenter commented Jun 21, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.17%. Comparing base (85db9d5) to head (a72eabb).

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main    #2098      +/-   ##
==========================================
- Coverage   81.28%   81.17%   -0.12%     
==========================================
  Files         128      127       -1     
  Lines       18925    18786     -139     
  Branches       12       12              
==========================================
- Hits        15384    15250     -134     
+ Misses       3538     3533       -5     
  Partials        3        3              
Flag Coverage Δ
docusaurus 61.84% <ø> (ø)
pester 86.07% <100.00%> (-0.02%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
scripts/linting/Test-ModelReferences.ps1 88.33% <100.00%> (ø)
scripts/linting/Update-ModelCatalog.ps1 83.33% <100.00%> (ø)

... and 7 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

- align PRD and BRD outputs to docs/project-planning
- update traceability and disclaimer guidance

📝 - Generated by Copilot
@WilliamBerryiii

WilliamBerryiii commented Jun 21, 2026

Copy link
Copy Markdown
Member

@jkim323 I pushed an additional update on this PR to cover the related project-planning guidance that surfaced while fixing the PRD Builder frontmatter issue.

What changed:

  • PRD Builder now writes generated PRDs under docs/project-planning/, keeps YAML frontmatter on line 1, places markdown suppression comments after the closing frontmatter delimiter, uses normalized phase skill keys, and ingests upstream BRD handoff coverage context when available.
  • BRD Builder now uses docs/project-planning/, defers frontmatter and section requirements to the canonical requirements-author templates, and aligns traceability language around business goals, FR-to-BG coverage, BG/DD identifiers, and quality gates.
  • The shared disclaimer-language instruction now applies to docs/project-planning/* so generated planning docs get the expected disclaimer guidance.

I also updated the linked issue and PR description to reflect the expanded scope. Validation passed with npm run lint:md, npm run lint:frontmatter, npm run lint:ai-artifacts, and VS Code diagnostics for the changed files.

@jkim323

jkim323 commented Jun 21, 2026

Copy link
Copy Markdown
Collaborator Author

Another change made for dt-agent. Moved DT coaching artifacts from copilot-tracking to docs/design-thinking/{project-slug}/. The state file (coaching-state.md) remains in .copilot-tracking/design-thinking-sessions/{project-slug}/ since it's ephemeral session state.

Artifacts under .copilot-tracking are gitignored and invisible to other agents. For ex, when the BRD agent needs DT outputs (stakeholder maps, synthesis themes, scope summaries) as input for requirements authoring, it had to re-ask the user for information that already existed in DT artifacts. Placing them under docs/design-thinking makes them accessible to any downstream agent (BRD, PRD, RPI) without repeating discovery questions.

cc @WilliamBerryiii

@github-actions

github-actions Bot commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

Eval Execution

Status: Passed — no merge-blocking failures (3 advisory assertion failure(s) present)

  • Artifacts evaluated: 3
  • Specs run: 3
  • Assertions passed: 9
  • Assertions failed (blocking): 0
  • Assertions failed (advisory): 3
  • Failed specs (merge-blocking): 0
Artifact Kind Status Specs Passed Failed (blocking) Failed (advisory)
dt-coach agent ⚠️ advisory-fail 1 3 0 1
brd-builder agent ⚠️ advisory-fail 1 3 0 1
prd-builder agent ⚠️ advisory-fail 1 3 0 1

Legend — ✅ clean · ⚠️ advisory failures only (non-blocking) · ⏭️ skipped · ❌ merge-blocking failure

Only Failed specs (merge-blocking) gates this PR. Advisory assertion failures are signal-quality checks captured during iteration; review them, but they do not block merge and may be acceptable.

@jkim323 jkim323 requested a review from rezatnoMsirhC June 26, 2026 05:22
@WilliamBerryiii WilliamBerryiii merged commit b5c695f into main Jun 26, 2026
80 checks passed
WilliamBerryiii added a commit that referenced this pull request Jun 29, 2026
## Description

Resolves a batch of documentation drift issues where prose docs and
READMEs fell behind code, agent, and path changes from recent PRs. Each
fix realigns stale references with the current source of truth:

* **BRD/PRD output path move** (PR #2098): updated lifecycle, role, and
planning docs to point at `docs/project-planning/` instead of the
retired `docs/brds/` and `docs/prds/`.
* **Eval CI behavior** (PRs #1834, #1949): documented shared-spec
tag-aware run behavior, the missing eval npm commands, and the `mixed`
stub mode plus sub-threshold `advisory-fail` status.
* **Copyright tooling** (PR #2169): documented the new
`CopyrightHeader.psm1` module and the `Test-CopyrightHeaders.ps1` `-Fix`
switch and canonical 2026 header format.
* **Collection helpers** (PR #1834): documented the new strict-safe
maturity vocabulary functions in `CollectionHelpers.psm1`.
* **rai-license-posture.instructions.md‎**: fix dead link and added
rai-license-posture instruction conformance stimulus to
`instructions.eval.yml`

## Related Issue(s)

Closes #2179
Closes #2180
Closes #2181
Closes #2182
Closes #2183
Closes #2187
Closes #2188
Closes #2191

## Type of Change

Select all that apply:

**Code & Documentation:**

* [ ] Bug fix (non-breaking change fixing an issue)
* [ ] New feature (non-breaking change adding functionality)
* [ ] Breaking change (fix or feature causing existing functionality to
change)
* [x] Documentation update

**Infrastructure & Configuration:**

* [ ] GitHub Actions workflow
* [ ] Linting configuration (markdown, PowerShell, etc.)
* [ ] Security configuration
* [ ] DevContainer configuration
* [ ] Dependency update

**AI Artifacts:**

* [ ] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
* [ ] Copilot instructions (`.github/instructions/*.instructions.md`)
* [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
* [ ] Copilot agent (`.github/agents/*.agent.md`)
* [ ] Copilot skill (`.github/skills/*/SKILL.md`)
* [ ] Copilot hook (`.github/hooks/*/*.json`)
* [x] Eval spec added/updated for changed AI artifacts (`evals/`)

**Other:**

* [ ] Script/automation (`.ps1`, `.sh`, `.py`)
* [ ] Other (please describe):

## Testing

<!-- Add manual testing descriptions when applicable. Run the
documentation validation commands below before merging. -->

## Checklist

### Required Checks

* [x] Documentation is updated (if applicable)
* [x] Files follow existing naming conventions
* [x] Changes are backwards compatible (if applicable)
* [ ] Tests added for new functionality (if applicable) (N/A —
documentation-only)

### Required Automated Checks

The following validation commands must pass before merging:

* [x] Markdown linting: `npm run lint:md`
* [x] Spell checking: `npm run spell-check`
* [x] Frontmatter validation: `npm run lint:frontmatter`
* [ ] Skill structure validation: `npm run validate:skills`
* [x] Link validation: `npm run lint:md-links`
* [ ] PowerShell analysis: `npm run lint:ps`
* [ ] Plugin freshness: `npm run plugin:generate`
* [ ] Docusaurus tests: `npm run docs:test`

## Security Considerations

* [x] This PR does not contain any sensitive or NDA information
* [ ] Any new dependencies have been reviewed for security issues (N/A —
no dependency changes)
* [ ] Security-related scripts follow the principle of least privilege
(N/A — no security scripts modified)

## Additional Notes

Documentation-only change. #2186 (DT Coach session-path rename) is
deliberately excluded from this batch.

---------

Co-authored-by: Bill Berry <WilliamBerryiii@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix: prd-builder agent file instruction

4 participants